MAKE_DLL

The MAKE_DLL procedure builds a sharable library from C language code which is suitable for use by IDL’s dynamic linking features such as CALL_EXTERNAL, LINKIMAGE, and dynamically loadable modules (DLMs). MAKE_DLL reduces the complexity of building sharable libraries by providing a stable cross-platform method for the user to describe the desired library, and issuing the necessary operating system commands to build the library.

Although MAKE_DLL is very convenient, it is not intended for use as a general purpose compiler. Instead, MAKE_DLL is specifically targeted to solving the most common IDL dynamic linking problem: building a sharable library from C language source files that are usable by IDL. Because of this, the following requirements apply:

You must have a C compiler installed on your system. It is easiest to use the compiler used to build IDL, because MAKE_DLL already knows how to use that compiler without any additional configuring. To determine which compiler was used, query the !MAKE_DLL system variable with a print statement such as the following:

PRINT, !MAKE_DLL.COMPILER_NAME

MAKE_DLL only compiles programs written in the C language; it does not understand Fortran, C++, or any other languages.
MAKE_DLL provides only the functionality necessary to build C code intended to be linked with IDL. Not every possible option supported by the C compiler or system linker is addressed, only those commonly needed by IDL-related C code.

MAKE_DLL solves the most common IDL-centric problem of linking C code with IDL. To do more than this or to use a different language requires a system-specific building process (e.g. make files or projects).

Examples

For more information on using MAKE_DLL, see Additional Examples.

Example 1: Testmodule DLM

The IDL distribution contains an example of a simple DLM (dynamically loadable module) in the external/dlm subdirectory. This example consists of a single C source file, and the desired sharable library exports a single function called IDL_Load. The following MAKE_DLL statement builds this sharable library, leaving the resulting file in the directory given by !MAKE_DLL.COMPILE_DIRECTORY:

; Locate the source file:

INDIR = FILEPATH('', SUBDIRECTORY=['external', 'dlm'])

; Build the sharable library:

MAKE_DLL, 'testmodule', 'IDL_Load', INPUT_DIRECTORY=INDIR

Syntax

MAKE_DLL, InputFiles [, OutputFile], ExportedRoutineNames [, CC=string] [, COMPILE_DIRECTORY=path] [, DLL_PATH=variable] [, EXPORTED_DATA=string] [, EXTRA_CFLAGS=string] [, EXTRA_LFLAGS=string] [, INPUT_DIRECTORY=path] [, LD=string] [, /NOCLEANUP] [, OUTPUT_DIRECTORY=path] [, /PLATFORM_EXTENSION] [, /REUSE_EXISTING] [, /SHOW_ALL_OUTPUT] [, /VERBOSE]

Arguments

InputFiles

A string (scalar or array) giving the names of the input C program files to be compiled by MAKE_DLL. These names should not include any directory path information or the .c suffix, they are the base file names.

The input directory is specified using the INPUT_DIRECTORY keyword, and the .c file suffix is assumed.

OutputFile

The base name of the resulting sharable library. This name should not include any directory path information or the sharable library suffix, which differs between platforms (for example: .so, .a, .sl, .exe, .dll).

The output directory can be specified using the OUTPUT_DIRECTORY keyword.

If the OutputFile argument is omitted, the first name given by InputFile is used as the base name of output file.

ExportedRoutineNames

A string (scalar or array) specifying the names of the routines to be exported (i.e., that are visible for linking) from the resulting sharable library.

Keywords

CC

If present, a template string to use in generating the C compiler commands to compile InputFiles. If CC is not specified, the value given by the !MAKE_DLL.CC system variable is used by default.

COMPILE_DIRECTORY

To build a sharable library, MAKE_DLL requires a place to create the necessary intermediate files and possibly the final library itself. If COMPILE_DIRECTORY is specified, the directory specified is used. If COMPILE_DIRECTORY is not specified, the directory given by the !MAKE_DLL.COMPILE_DIRECTORY system variable is used.

DLL_PATH

If present, the name of a variable to receive the complete file path for the newly created sharable library. The location of the resulting sharable library depends on the setting of the OUTPUT_DIRECTORY or COMPILE_DIRECTORY keywords as well as the !MAKE_DLL.COMPILE_DIRECTORY system variable, and different platforms use different file suffixes to indicate sharable libraries. Use of the DLL_PATH keyword makes it possible to determine the resulting file path in a simple and portable manner.

EXPORTED_DATA

A string (scalar or array) containing the names of variables to be exported (i.e., are visible for linking) from the resulting sharable library.

EXTRA_CFLAGS

If present, a string supplying extra options for the command used to execute the C compiler to compile the files given by InputFiles. This keyword is frequently used to specify header file include directories. This text is inserted in place of the %X format code in the compile string.

EXTRA_LFLAGS

If present, a string supplying extra options for the command used to execute the linker when combining the object files to produce the sharable library. This keyword is frequently used to specify libraries to be included in the link, and is inserted in place of the %X format code in the linker string.

INPUT_DIRECTORY

If present, the path to the directory containing the source C files listed in InputFiles. If INPUT_DIRECTORY is not specified, the directory given by COMPILE_DIRECTORY is assumed to contain the files.

LD

If present, a template string to use when generating the linker command to generate the resulting sharable library. If LD is not specified, the value given by the !MAKE_DLL.LD system variable is used by default.

NOCLEANUP

To produce a sharable library, MAKE_DLL produces several intermediate files:

A shell script (UNIX) or batch file (Windows) that is then executed via SPAWN to build the library.
A linker options file. This file is used to control the linker. MAKE_DLL uses it to cause the routines given by the ExportedRoutineNames argument (and EXPORTED_DATA keyword) to be exported from the resulting sharable library. The general platform terminology is shown below.

Platform	Linker Options File Terminology
UNIX	export file, or linker map file
Windows	a `.DEF` file

Object files, resulting from compiling the source C files given by the InputFiles argument.
A log file that captures the output from executing the script, and which can be used for debugging in case of error.

By default, MAKE_DLL deletes all of these intermediate files once the sharable library has been successfully built. Setting the NOCLEANUP keyword prevents MAKE_DLL from removing them.

Note: Set the NOCLEANUP keyword (possibly in conjunction with VERBOSE) for troubleshooting, or to read the files for additional information on how MAKE_DLL works.

OUTPUT_DIRECTORY

By default, MAKE_DLL creates the resulting sharable library in the compile directory specified by the COMPILE_DIRECTORY keyword or the !MAKE_DLL.COMPILE_DIRECTORY system variable. The OUTPUT_DIRECTORY keyword can be used to override this and explicitly specify where the library file should go.

PLATFORM_EXTENSION

Set this keyword to use a platform-specific library naming scheme. Using platform-specific library names allows IDL to select the correct library for the current platform from multiple library files residing in the same directory. See DLMs for details.

REUSE_EXISTING

If this keyword is set, and the sharable library file specified by OutputFile already exists, MAKE_DLL returns without building the sharable library again. Use this keyword in situations where you wish to ensure that a library exists, but only want to build it if it does not. Combining the REUSE_EXISTING and DLL_PATH keywords allows you to get a path to the library in a platform independent manner, building the library only if necessary.

SHOW_ALL_OUTPUT

MAKE_DLL normally produces no output unless an error prevents successful building of the sharable library. Set SHOW_ALL_OUTPUT to see all output produced by the spawned process building the library.

VERBOSE

If set, VERBOSE causes MAKE_DLL to issue informational messages as it carries out the task of building the sharable library. These messages include information on the intermediate files created to build the library and how they are used.

Additional Examples

Example 2: Using GCC

IDL is built with the standard vendor-supported C compiler in order to get maximum integration with the target system. MAKE_DLL assumes that you have the same compiler installed on your system and its defaults are targeted to use it. To use other compilers, you tell MAKE_DLL how to use them.

For example, many IDL users have the gcc compiler installed on their systems. This example shows how to use gcc to build the testmodule sharable library from the previous example:

; We need the include directory for the IDL export.h header

; file. One way to get this is to extract it from the

; !MAKE_DLL system variable using the STREGEX function

INCLUDE=STREGEX(!MAKE_DLL.CC, '-I[^ ]+', /EXTRACT)

; Locate the source file